This program is shareware. It may be freely distributed via online services and bulletin boards if it is unmodified and includes the "Newt ReadMe" file. It may not be commercially bundled or redistributed on CD-ROM, floppy disk or PCMCIA without my permission. After several days of trial use, please register your copy by sending $15 to the author.
Please read the rest of this file for help, examples, warnings and other information.
After several days of trial use, please register your copy by sending $15 to the author. In return, I will provide you with information about several additional features, a mini-tutorial on Newton Script, and first access to future updates. Comments, suggestions also appreciated.
Stephen Weyer
17 Timber Knoll Drive
Washington Crossing, PA 18977
Internet: weyer@guest.apple.com
America Online: SteveWeyer
AppleLink: WEYER.S
Newt vs. Turtle
-----
"Newton Turtle" and "NewtTurtle" seemed a bit too long, so I decided to shorten its name to "Newt", especially given its amphibious similarity to its Logo cousin.
So that Newt can appeal to many groups, it is gender "newtral" (perhaps even "newtered"). Most references herein will be to "Newt" or "it".
Newton Script
-----
Newton Script is Newton's object-oriented implementation language (basic atomic objects are "newtrons"?) This package allows you to write your own expressions/ scripts/methods and execute them directly on your Newton. This assumes some familiarity with programming concepts and languages, such as Logo since commands names are similar though syntax is different. Since I provide little description of Newton syntax or other functions, I strongly recommend that you stay reasonably close to the examples that I provide (or register to obtain a somewhat longer introduction, or you can buy the Newton ToolKit (NTK) and docs from APDA for $800).
WARNING
-----
There's an obvious benefit vs. risk tradeoff here. Exploring "mathematics microworlds" and doing problem solving by writing programs are "powerful ideas" (Seymour Papert). At the same time, "a little learning [about programming] is a dangerous thing" (with apologies to Alexander Pope). Though unlikely, you could, through careless experimentation, mess up the innards of your Newton by removing soups and zapping frames.
If you exercise some common sense, and stay within the commands and syntax I have suggested, I hope you have many hours of learning enjoyment.
At the same time, given the litigious nature of our society that yearns for risk without responsibility, I feel compelled to add the following warning (repeated in other variations several places later):
>>> WARNING: USE THIS PACKAGE AT YOUR OWN RISK! <<<
Hey, what's life without a little risk anyway? Have fun!
Shareware vs. Freeware
-----
Newt is my first shareware offering (earlier, I distributed a freeware game "PicoFermiBagels"). If you would like to encourage me to develop and release subsequent versions of Newt (e.g., with more documentation on current features and Newton Script, more source examples, and new features), then please show your support by sending in the shareware fee along with suggestions, bug reports and comments. I had debated whether to "cripple" this version by not allowing you to save any or many methods. However, I'd rather spend time my time figuring out how to enable rather than disable features. Thanks.
Teaching Mathematics and Problem Solving
-----
Although I have written Logo curriculum for turtles, Legos, and other domains, this document provides only a few isolated examples. I would encourage you to experiment, and to translate ideas and code from Logo materials and books, e.g., Abelson & diSessa.
=====
INTERFACE GUIDE
Main View
----
• Erase: erases Newt's drawing area; leaves Newt in same position.
• <scrub in draw area>: also erases everything
• Home: teleports Newt to center, pointing up, with same pen setting
• <tap in draw area>: Newt will go to location of pen using current Pen setting, preserving heading. follow this with a scrub to give Newt a clean slate.
• Pen: pen thickness used in drawing (default: 1). 0 means Newt just moves (no line).
(saved as a Preference -- see Preferences).
• Newt?: if checked (default: true), displays Newt with its tip at current x,y, pointing in current direction, and "xor-ed" so not to interfere with current drawing. Turn off for faster drawing. (saved as a Preference).
• Redraw: if checked (default: true), Newt maintains a display list. This means that subsequent drawing will be restored after various events that might erase or obscure your screen such as visiting another view (About or Define), dragging a keyboard, closing an error window, or after waking your Newton. If you plan to erase and draw something different anyway, turning this off would save memory. (saved as a Preference).
• Times: the value in this field (default: 0) can be used as a "times" variable in the Eval field. The "Times" button uses this value for built-in iteration, e.g., if Times=4, Dist=40,Deg=90, tapping on Times tells Newt to :go(40) then :turn(90) 4 times, i.e., making a square -- the Newton Script is written to the "Eval" field where it is executed (and you can edit it if you like). Tap "Deg" to turn, then tap Times or Eval again.
• Dist: the value in this field (default: 0) can be used as a "dist" variable in the Eval field. The "Dist" button uses this value for distance, e.g., if Dist=20, tapping on Dist tells Newt to :go(20), moving 20 in the "forward" direction (i.e., along Newt's current heading). This draws a line if Pen is a number. A negative value just means go "backward". To give you some idea of scale, Newt's drawing area is roughly 200x200. Newt will clip at its drawing boundary.
• Deg: the value in this field (default: 0) can be used as a "deg" variable in the Eval field. The "Deg" button uses this value for degrees, e.g., if Deg=90, tapping on Deg tells Newt to :turn(90), turning right by 90 degrees. A negative value just means turn "left". Newt will "mod" your number to prevent dizziness.
[note: Extra spaces between digits for Times, Dist and Deg are ignored. Decimal points may be included, though the times value is rounded]
• Eval: this field can contain a short program in Newton Script to be executed by tapping the "Eval" button. Because of syntactic punctuation, it's probably best to double-tap to get the keyboard. You can also use the names "times", "dist" and "deg", so if you change those values you can just Eval your expression again. You can also edit this field as a method ("evalField") in the Define area where there's a larger area. The keyboard may prompt you about adding new words or expressions to your dictionary -- tip: if you put spaces before and after parentheses, and after commas, the variable and method names offered will be more useful. Eval button remains highlighted during execution.
I will not attempt to provide a complete description of Newton Script here -- I assume that either you're already familiar with it, have access to NTK documentation, or that you can figure out the syntax and sample commands from the examples and descriptions below. Depending on demand, I can provide a mini-tutorial for more advanced manipulation of your Newt.
WARNING: IF YOU USE OTHER SYSTEM FRAMES, METHODS, AND FUNCTIONS, YOU DO SO AT YOUR OWN RISK.
Since NS is an object-oriented language, your programs or scripts are defined as "methods" on "newtView". You tell Newt to do things by sending it a "message", e.g., "go". You precede a message with a colon (:) and include zero or more parameters, i.e., values for variables. For example, :go(50). There are "slots" that contain values that you can access, such as "times", "dist", and "deg". Here are some examples
Examples:
:poly (4,100) // draws a 4-sided polygon, where 100 = length of each side
:poly (times,dist) // uses values in Times and Dist fields for poly
for i:=1 to times do begin :go (dist); :turn (deg); end // when you click on "Times"
:squiral (18,100) // draw 18 squares(each side 100), turning 360/18 after each
for sides:=3 to 10 do :poly (sides,dist) // nested polys
:erase (); :poly (Random(3,15),Random(10,20)) // a random poly. sep mult stmts with ;
for i:=5 to 160 by 5 do begin :go(i); :turn(90); :beep(); end // version of Newt icon
[Implementation note: these methods and slots are defined on the "newtView" frame. Though normally you send a message to a specific frame, i.e., frame:message, it isn't necessary since these are sent implicitly to Newt. Similarly, the slot values are accessible in context through inheritance, so you do not need to specify the frame where they reside, i.e., frame.slot]
If you spell something incorrectly, or use incorrect syntax or parameters, you will most likely get a Newton error box with a cryptic code. A list of error codes near the end of this document may help a little, but basically you'll have to take a closer look at what you wrote, edit it and try again.
WARNING: I DO NOT PROVIDE A GENERAL INTERRUPT CAPABILITY (BEYOND THE MANUAL RESET BUTTON IN THE BACK). I SUGGEST COMMON SENSE IN CHOOSING VALUES FOR ITERATION, RECURSION OR DISTANCE THAT ARE NOT "TOO LARGE". I will generally provide some reasonable values to try. There is a way to rewrite methods to be interruptible, but that's an advanced topic.
• Define: define your own methods. see INTERFACE GUIDE: Define Screen later.
=====
Preferences
Newt saves your preferences for Pen, Newt? and Redraw in a "system soup" entry so that it can potentially persist across Newt sessions (sending the messages :pen, :visible, and :redraw does not save the values, nor reflected in the screen choices). If you do not Save any source methods within the Define Screen, then Newt will automatically remove this preference entry when you quit (and automatically recreate it with the last settings if you start again). If you Save any existing or new methods, these also go into the preference entry. However, the preference entry would then persist until 1) you Remove all methods (including poly and squiral) and then quit Newt; or 2) you use your favorite soup cleaning utility to remove it manually (entry tag: "NewtTurtle" in the system soup). I hope this provides a reasonable default for cleaning up after casual users (who write no methods) vs. preserving settings and source for others.
=====
METHOD DESCRIPTION
Basic Newt Methods
-----
• :beep()
Newt beeps/squeaks
• :erase()
erase Newt's drawing area
• :go(distance)
move Newt <distance> from current location, forward if positive <distance>, backward if negative <distance>. if Pen is a number, draws a line. From center, Newt can go ~100 before reaching edge of drawing area. Newt just clips the line and disappears if you command it to go outside .
• :goPt(x,y)
move Newt to a point relative to center (0,0). 50,50 would be 50 dots to the right and up (in Newt's coordinate system, y increases from bottom to top)
• :home()
move Newt to center, pointing up, ignoring but preserving current pen setting
• :pen(num)
set size of pen. typical values are 0,1,2,3. [note: not saved as a Preference].
• :pendown()
same as :pen(1)
• :penup()
same as :pen(0)
• :turn(degrees)
turn Newt <degrees> from current heading: positive<degrees> turns Newt to right, negative to left.
• :turnTo(degrees)
turn Newt to an absolute heading, typically between 0 and 359. 0 is "straight up".
Other/Advanced Newt Methods
-----
• :cCurve(...)
a doubly-recursive, fractal-like method. some examples to try:
:cCurve(6,8,0)
:cCurve(8,4,0)
try larger numbers at your own risk. contact author for documentation and source
• :poly(sides,len)
draw a polygon, e.g., :poly(6,50) is a hexagon. :poly(times,dist) to use edit fields.
source provided
• :redraw(flag)
set redraw, i.e., maintain display list if flag=true. [note: not saved as preference]
• :squiral(num,len)
draw a square(poly(4,len)), then turn(360/num); do this num times. source provided
• :squiral2(num,len)
an interruptible version of squiral. e.g., :squiral2(30,80)). Once it starts, Eval button unhilites, Stop Button appears. you could change the Pen setting during execution, and/or hit the Stop button to stop Newt. contact author for details about converting iterative and recursive methods to be interruptible.
• :visible(flag).
if flag is True, then show Newt. if flag is nil, hide Newt. [not saved as preference].
User-Defined Methods
-----
After trying some of the earlier examples, if you're at all comfortable with the subset of Newton Script that I've shown so far, you should be ready to add and edit your own methods. At its simplest, a method could be used to create commands that you're more familiar with, e.g., to mimic your favorite dialect of Logo. For example, "fd" and "bk" as synonyms for "go", or more complicated behavior like "spiral" or "house". For this to work, your expression should begin with "func", followed by a list of any parameters in parentheses, followed by a single statement, which can be a "begin ... end" construct. You supply any method arguments in the parens following "func", e.g., we might define "fd" as "func(distance) :go(distance)". You edit these method definitions on the Define screen, described next.
=====
USER INTERFACE
Define Screen
-----
• Edit: the field to the right of the "Edit" button contains the name of the method you would like to edit. You can write in a new name or select an existing method (for which there is source) by tapping the diamond. Source for poly and squiral are provided. You can also edit "evalField", which gets saved back to the main screen (where you can include multiple expressions separated by semicolon (;), but don't precede with "func()" as for the real methods). Method names begin with alphabetic characters (case is preserved but ignored) and can contain numbers. The colon(:) is not part of the name for definition, it is just used when invoking it. Remember to tap the "Edit" button after selecting or entering a name. New methods will provide a basic "func () begin end" template. Attempting to Edit a "system" method (i.e., for which there is no source), an empty name or a name not beginning with an alphabetic character will result in a beep. Similar checks are done for Remove and Save.
• Remove: When a name is supplied in the Edit field, you can Remove any methods that have source, including poly and squiral -- I'd recommend not removing poly if you plan to use squiral or squiral2. This removes both the source and compiled versions. Since the button is "out of the way", I currently do not provide a warning after you tap it. However, if you do an Edit first, the source is still in the source area in case you change your mind and want to Save it again as the same name (or as a different name, which is the way to do "Rename"). Note: when you remove all methods (including poly and squiral), Newt will remove the preference entry when you quit. You can apparently remove "evalField", but not really.
• Save: Once you have begun to edit the method, the "Save" and "Revert" buttons appear (and the "Edit" and "Remove" buttons and closebox disappear). When you tap on "Save", Newt will compile the method and save your source if successful. Note that it uses the name currently in the "Edit" field, so one way to copy a method is to "Edit" it, then change the name and make any change to the method, and then "Save".
[note: when you Save, you may get a beep for an invalid method name. If Newton is unsuccessful at compiling your code, you'll get an error box (see earlier description under "Eval" and later under "Errors"). When successful, the source is saved in the Newt preferences entry (in the system soup). Each time Newt is started, it compiles all of the method sources that it finds there so that you can use them immediately.]
• Revert: If you wish to discard any edits you have made since the last Save, just tap "Revert" (warning: there is no warning/confirmation). The last-saved source is then displayed for the method named in the "Edit" field (usually the current method, but it could be the name of the next method you want to view).
• <close box>: This disappears when you begin to edit source. After a "Save" or "Revert", it reappears thus allowing you to exit the Define screen.
• <source area>: This is just a "paragraph view" for writing and typing. Double tap to get standard keyboard. A future version may include programmable buttons with code snippets (or maybe someone will just write a generic, smart, multiple clipboard).
=====
Errors
-----
In the unlikely event that a system box pops up with a cryptic error code, check the following partial list of common error codes, and see if there might be something missing or extra in one of your values or expressions.
Code Description
-8007: syntax error (from compiler)
-48404: expected a number
-48402: expected an integer
-48803: wrong number of arguments
-48807: undefined variable
-48809: undefined method
1627052: divide by zero
If you have a Macintosh, you might also want to get the "LowDown" DA, available from one of the usual Newton libraries/ftp archives/bboards, that provides a more complete list of errors from the NTK docs.
Things to try: check your syntax against those in examples, check spelling for method and variable names, check number of arguments, check type of arguments (e.g., float vs. integer). If you think it's really a problem with Newt, send me mail describing what you had entered, and I'll try to respond within a day or two.
=====
Possible Next Steps
-----
There are many features/fixes that would be nice to have. However, there are design tradeoffs, esp. given the MessagePad's constraints. So, help me figure out:
• where does it go on the screen?
• is it worth the extra memory space?
• can it take advantage of existing Newton mechanisms or metaphors?
Some possibilities:
• online help (this readme file ~20K)
• tuning recognizer for code (e.g., no prompting for dictionary additions?)
• more gestural input
• save code in another soup (e.g., Notes to take advantage of printing, beaming, etc.)
• misc. interface cleanup (e.g., confirm Revert and Remove ?)
• multiple Newts (maybe when there's a bigger color screen?)
• misc. drawing features (e.g., pen mode (xor, etc.))
• more examples, documentation,...
• streamline code editing (macro buttons or customized keyboard)
• a print area (and subset of string/list Logo equivalent commands)
In addition to suggestions and opinions, pointers to documentation and examples would be greatly appreciated.
=====
History/Credits
I first implemented a screen turtle on an IMLAC display computer, accessed from BBN Logo on a DEC PDP-10 circa 1972 (wow, that makes me feel ancient). Subsequently, I implemented other versions in Lisp, and used others in Smalltalk and ObjectLogo.
The two tiny NTK examples, Dot2Dot and InspectorGadget, with a little creative juxtaposition, started me down this path.
Apple deserves credit for creating an exciting product (Newton) and powerful development environment (NTK) and I look forward to better documentation and even more examples. Newton and Newton ToolKit are trademarks of Apple Computer.
Finally, my family deserves credit for giving me the evening and weekend time to explore this; Ellie helped with testing.
